COMMENT ⊗   VALID 00005 PAGES
C REC  PAGE   DESCRIPTION
C00001 00001
C00002 00002		IIIPOX - Vector Graphics to POX Macro Conversion System
C00005 00003	.al txt,mlb
C00007 00004	\|\\@IIIPOX.POX[1,3]\
C00008 00005
C00014 ENDMK
C⊗;
	IIIPOX - Vector Graphics to POX Macro Conversion System

IIIPOX is a program  for taking a conventional  vector graphic binary file  and
producing a  POX source  file which  defines an  overlay to  generate the  line
drawing given in the original file.  The purpose of doing this is to allow  the
user to include complex diagrams in documents compiled with POX.  All of  POX's
text formatting capabilities  are thus available  to the user.   For example  a
diagram may be centered or fancy labels overlaid on it.

A "conventional vector graphic binary file" is a file consisting of the sort of
command words that are used by the III display processor.  Many programs  which
draw pictures generate files in this format.  (A notable exception is SUDS, the
engineering drawing system, which has its own format).  These files go by  many
different names, here they will be called "display files" for short.

IIIPOX consists of  a SAIL program  and a POX  vector graphic macro  definition
file.  The SAIL program reads  in a display file and  outputs a POX file.   The
output file uses the predefined macros to build the corresponding overlay.  The
user may then include the overlay in subsequent text.

The next page gives a sample run for a display file consisting of an  invisible
vector to (-384,-384)  followed by  visible vector to  (+384,+384) (in  display
co-ordinates).  The following page shows the  resulting POX file.  The text  of
this explanation resumes on the next page thereafter.

.al txt,mlb

.r iiipox

	⊗⊗⊗⊗⊗⊗⊗⊗       III to POX file converter       ⊗⊗⊗⊗⊗⊗⊗⊗

III Display Buffer Input File (DSK:DPYBUF.DPY[TXT,MLB]) : demo

	Reading DSK:DEMO.DPY[TXT,MLB]

POX Vector Macro Output File  (DSK:DEMO.POX[TXT,MLB]) : 

	File DSK:DEMO.POX[TXT,MLB] already exists. Replace ? (Y) : 

	Writing DSK:DEMO.POX[TXT,MLB]

	2 III command words in file.

POX overlay name ? (DEMO) : 

	Mapping is [(-512,-512),(512,512)]
	into       [(0,0),(1024,1024)]

Change III to POX Transform ? (N) : 

Working ...Done.

Again, Edit or Quit ? (E) : 

Say <CONTRL><META>X RUN to E to restart.

NEED TO REFORMAT DEMO.POX. OK?y

 Rippling  ...

\|\\@IIIPOX.POX[1,3];\
\ \
\	From DSK:DEMO.DPY[TXT,MLB]
\	on 14 NOV 1977 at 11:03 Pm
\
\	Mapping is [(-512,-512),(512,512)]
\	into       [(0,0),(1024,1024)]
\
\!VClear;\
\
\!VI(128,896);\!VV(896,128);\
\ \
\&DEMO←VL,00;\!VClear;\
\

Items appearing in parentheses are defaults.  The filenames are parsed using  a
routine written  by KS.   If  just a  portion  of a  filename  is given  it  is
substituted into the corresponding place in the default file name.

There are many ways that the overlay defined on the last page could be used.
A simple example would be to have another POX file containing the commands

\|\\M0FIX25;\F0\	Define the brick character and a font and select the font
\@DEMO.POX[TXT,MLB];\	Call for the overlay definition
\			Place the overlay near the top of the page in the center
\C\HDEMO;
\			Put a centered title under it
\CWhat a line !!!

More complicated things can be done as well, see the POX manual for details.

About the  only aspect  of  the program  which is  not  fairly obvious  is  the
co-ordinate transform.  It's purpose  is to allow the  user to specify how  the
display co-ordinates relate to page co-ordinates.  Display co-ordinates go from
-512 to +512 for a full screen.  POX co-ordinates are in XGP pixels, which  are
1/200 inch.  Therefore, the default transform  maps a full screen picture in  a
one-to-one fashion into a  square 5.12 inches  on a side.   To change the  size
(and possibly  the positioning)  of a  display we  change the  transform.   For
instance, to map  the lower right  screen quadrant  into a 8.5  inch square  we
would change the transform to

[(0,-512),(512,0)] → [(0,0),(1700,1700)]

The four numbers in the lists correspond to XLo,YLo and XHi,YHi - the lower left
and upper right corners of a rectangle.  The lists are also defaulted.  For each
one the user may type a list of from zero to four values.  These are substituted
for the default values in the order given.

There are some limitations and restrictions the user should be aware of :

	Many III commands make no sense when translated to the hardcopy medium.
	Others may be translated, but only by the user (eg change brightness =
	change font).  IIIPOX will output such commands as comments.

	Text in the display file is passed to a special macro.  It will  appear
	in the resulting  overlay in the  "current" font unless  the user  does
	something like edit the call to include a font select.  Also, the  text
	probably will cause problems if it  contains curly brackets "{" &  "}",
	or the brick character "\".

	Dots ("end  point  vectors")  are  drawn  as  short  diagonal  strokes,
	oriented like  a backslash  (\) with  the lower  right end  at the  dot
	co-ordinate.  (Single pixel XGP dots  are often invisible or  disappear
	in the noise).

	The POX macros use the x,y,X,Y and Z registers.  Most of the macros and
	internal overlays  have names  beginning with  capital "V".   The  only
	exception is the ubiquitous EVAL.  See the IIIPOX.POX file for details.

Finally the user will process the file with POX, resulting in an XGP file.   If
the figures are at all complex XSPOOLing the file often does not work (too many
vectors for the server to handle at  once).  Sometimes you can get around  this
by setting the NVNODES switch in the XSPOOL command to some big number.

Usually, though, it is best to list the file using XGPSYN.  There are two  ways
to do  this.  The  first is  to start  XGPSYN on  your file  and give  the  "L"
command.  This will cause the  WHOLE file to be listed  on the XGP.  To list  a
SINGLE page start XGPSYN as usual, give the "B" command, then the page you want
(it will display  a corner  on the video  synthesizer), then  the "X"  command.
Either way the size of your job will reach dramatic heights.

[Note:	other people (eg BES) have at various times written similar programs. If
	IIIPOX is not your cup of tea try asking around.]

IIIPOX was written by MLB.